"""
提示词工程模块接口定义
将提示词工程分解为可插拔的模块（分析、设计、评估、优化）
支持自定义组件，允许用户扩展功能
"""

from abc import ABC, abstractmethod
from typing import Dict, Any, Optional, List, Union
from src.research_core.prompt_eng_state import PromptEngineeringState


class IPromptEngineeringModule(ABC):
    """
    提示词工程模块基础接口
    定义所有提示词工程模块的基本契约
    """
    
    @abstractmethod
    def get_name(self) -> str:
        """
        获取模块名称
        
        Returns:
            模块名称
        """
        pass
    
    @abstractmethod
    def get_description(self) -> str:
        """
        获取模块描述
        
        Returns:
            模块描述
        """
        pass


class IRequirementAnalysisModule(IPromptEngineeringModule):
    """
    需求分析模块接口
    负责分析用户需求并生成分析报告
    """
    
    @abstractmethod
    def analyze_requirement(self, requirement: str) -> Dict[str, Any]:
        """
        分析用户需求
        
        Args:
            requirement: 用户需求描述
            
        Returns:
            需求分析结果
        """
        pass


class IPromptDesignModule(IPromptEngineeringModule):
    """
    提示词设计模块接口
    负责根据需求分析设计初始提示词
    """
    
    @abstractmethod
    def design_prompt(self, requirement_analysis: str, context_info: Optional[Dict[str, Any]] = None) -> str:
        """
        设计提示词
        
        Args:
            requirement_analysis: 需求分析结果
            context_info: 上下文信息
            
        Returns:
            设计的提示词
        """
        pass


class IPromptEvaluationModule(IPromptEngineeringModule):
    """
    提示词评估模块接口
    负责评估提示词质量
    """
    
    @abstractmethod
    def evaluate_prompt(self, prompt: str, requirement: str) -> Dict[str, Any]:
        """
        评估提示词质量
        
        Args:
            prompt: 要评估的提示词
            requirement: 原始需求
            
        Returns:
            评估结果字典
        """
        pass


class IPromptOptimizationModule(IPromptEngineeringModule):
    """
    提示词优化模块接口
    负责优化提示词
    """
    
    @abstractmethod
    def optimize_prompt(self, prompt: str, evaluation_result: Dict[str, Any], 
                       feedback: Optional[str] = None) -> Union[str, Dict[str, Any]]:
        """
        优化提示词
        
        Args:
            prompt: 原始提示词
            evaluation_result: 评估结果
            feedback: 人工反馈（可选）
            
        Returns:
            优化后的提示词或包含优化结果的字典
        """
        pass


class IHummanFeedbackModule(IPromptEngineeringModule):
    """
    人工反馈处理模块接口
    负责处理人工反馈信息
    """
    
    @abstractmethod
    def process_feedback(self, feedback: str) -> Dict[str, Any]:
        """
        处理人工反馈
        
        Args:
            feedback: 人工反馈内容
            
        Returns:
            处理结果
        """
        pass


class IPromptEngineeringModuleFactory(ABC):
    """
    提示词工程模块工厂接口
    负责创建和管理提示词工程模块实例
    """
    
    @abstractmethod
    def create_module(self, module_type: str, config: Optional[Dict[str, Any]] = None) -> IPromptEngineeringModule:
        """
        创建模块实例
        
        Args:
            module_type: 模块类型
            config: 配置信息（可选）
            
        Returns:
            模块实例
        """
        pass
    
    @abstractmethod
    def register_module(self, module_type: str, module_class: type):
        """
        注册模块实现类
        
        Args:
            module_type: 模块类型
            module_class: 模块实现类
        """
        pass
    
    @abstractmethod
    def get_available_modules(self) -> List[str]:
        """
        获取可用模块列表
        
        Returns:
            可用模块类型列表
        """
        pass


# 默认模块实现


class BasePromptEngineeringModule(IPromptEngineeringModule):
    """
    基础提示词工程模块实现
    提供模块接口的基本实现
    """
    
    def __init__(self, name: str, description: str):
        self._name = name
        self._description = description
    
    def get_name(self) -> str:
        return self._name
    
    def get_description(self) -> str:
        return self._description
    
    def can_handle(self, state: PromptEngineeringState) -> bool:
        # 默认实现：可以处理任何状态
        return True


# 导出接口和类
__all__ = [
    'IPromptEngineeringModule',
    'IRequirementAnalysisModule',
    'IPromptDesignModule',
    'IPromptEvaluationModule',
    'IPromptOptimizationModule',
    'IHummanFeedbackModule',
    'IPromptEngineeringModuleFactory',
    'BasePromptEngineeringModule'
]